AppleTalk  *250*

Prograph's AppleTalk primitives provide a vastly simplified interface for accomplishing the most common network tasks - registering on the network, finding out what other nodes are out there on the network, and sending textual data between programs on the network. It is not necessary to read Inside Macintosh to use these primitives. 

A SPECIAL NOTE ABOUT ATP:  The AppleTalk Transaction Protocol is a protocol for delivering data between nodes on an AppleTalk network.  The AppleTalk Manager toolbox calls are described in Inside Macintosh . Detailed information about AppleTalk protocols is available in Inside AppleTalk.

Loading AppleTalk Primitives

AppleTalk primitives are stored in the Communication Primitives file, located in the Disabled Primitives folder, a subfolder in the Prograph Extensions folder.  These primitives are not initially loaded with Prograph Classic, as packaged.  

NOTE:  The Communication Primitives file also contains the Serial Port primitives.
In order to use the AppleTalk primitives, shut down Prograph and move the  Communication Primitives file into the Prograph Extensions folder. You may have to increase Prograph's minimum memory allocation using Finder's Get Info dialog.  The AppleTalk primitives are enabled the next time you start Prograph.

Using AppleTalk Primitives  *250*

Network-aware programs are either clients, server programs, or both. All of these must call ATP-Open and NBP-Open sometime after starting up, and before using any other AppleTalk primitives. The next step is usually to call NBP-Register to make the program's name and type known to other programs on the network. Note that the program type can be any string you like. It allows you to later query the network to find out all programs of a certain type that are running on the network.

Once registered, server programs use ATP-Get-Request periodically (i.e. at idle time) to check for client-side requests being sent. When a request is received, the server uses ATP-Send-Response to reply to the client. On the other side, client programs wait for some user action or other event to precipitate sending a request to a server with ATP-Send-Request. After the request is sent, the client must check periodically for the server's response with ATP-Get-Response.

The contents of the request and response strings are entirely up to the client and server programs. Usually you would define your own “code words” for the requests and responses. If you are working with an existing server program, it should have documented which requests it understands, and the format of the responses.

AppleTalk Errors  *251*

Every AppleTalk primitive returns an integer error code. Zero means success; otherwise, an error has occurred. Error numbers may be one of those documented in Inside Macintosh, or one of the following:

Error Number Description 

1
The AppleTalk protocol is already active

2
Both NBP and ATP must be open

3
The port is not configured for AppleTalk

4
Unable to open AppleTalk because AppleTalk is inactive

5
The Correct versions of the AppleTalk drivers are unavailable

6
Unable to execute server only primitives from a client

7
Unable to execute client only primitive from a server

8
Unable to locate entity

9
Unable to respond to the client

10
Attempting to register on AppleTalk under more than one name

11
Unknown error

12
Memory error

13
Entity not found

_________________________________________________
                        
                                    ATP-Close
 *251*

Output types:  integer

Description:  Closes AppleTalk under ATP. If you have called ATP-Open, you must call ATP-Close before quitting your application.

See also: ATP-Open

_________________________________________________

                                             ATP-Get-Request
*252*

Input type: 
boolean

Output types:  list; string; integer

Description:  Used by server-side applications to check whether a request has been sent by a client. If AutoRespond is true, a response will automatically be sent, containing the default message “OKAY”. Sender is a list of three integers which identify the sender. This list should be passed into ATP-Send-Response. 

See also:  ATP-Send-Response

_________________________________________________

                                                ATP-Get-Response
*252*

Output types: 
list; string; integer

Description: 
Used by client-side applications to check for a server's response after the client has sent a request. If no responses are available, Message and Sender are NULL. Otherwise, Sender is in the form of a list of three strings: (Name Type Zone).

See also:  ATP-Send-Request

_________________________________________________

                                             ATP-Open
 *252*

Input types: string; boolean

Output types: integer

Description: Opens AppleTalk under ATP. Must be called before using any of the other ATP primitives. NodeType may be “server”, “client” or “both”. If SelfSend is TRUE, the node is able to send to itself.

See also: ATP-Close

_________________________________________________

                                           ATP-Send-Request
*253*

Input names:  Servers; Request; [Count; Interval]

Input types: 
list of ( Name [Type [Zone]] ); string; [ integer; integer ]

Defaults: Count = 2; Interval = 8; Type = "=" (current type); Zone = "*" (all zones)

Output types: integer

Description: 
Used by client-side applications to send a Request to a list of Servers. Each server identifier in the list is itself a list of one to three strings: (Name [Type [Zone]]). Use NBP-Lookup to obtain a list of which servers are available on the network. A value of “*” for Type means the request will be sent to all registered applications; “=” means it will be sent to applications with the same type as the sending application only. A value of “*” for Zone means all zones; “=” means the current zone only. Count is the number of retries. Interval is the number of seconds between retries.

See also:  ATP-Get-Response, NBP-Lookup

_________________________________________________

                                            ATP-Send-Response
*253*

Input names: Client; Response; [ Count; Interval ]

Input types: list of integer; string; [ integer; integer ]

Defaults:  Count = 2; Interval = 8

Output types: integer

Description: Used by a server-side application to send Response to Client. Client is the list of integers returned as the Sender by ATP-Get-Request. Count is the number of retries. Interval is the number of seconds between retries.

See also:  ATP-Get-Request

_________________________________________________

                                     NBP-Close
 *254*

Output types: integer

Description:  Closes AppleTalk under NBP. If you previously called NBP-Open, you must call NBP-Close before quitting your application.

See also:  NBP-Open

_________________________________________________

                                  NBP-Confirm
*254*

Input names: 
Name; [ Type; Zone; Count; Interval ]

Input types: 
string; [ string; string; integer; integer ]

Defaults: Type = "=" (current type); Zone = "*" (all zones); Count = 2; Interval = 8

Output types:  integer

Description: Confirms that a node is still on the network. Confirms the existence of Name of Type in Zone. Count is the number of retries. Interval is the number of seconds between retries. If node is confirmed, Error is 0; otherwise, Error is 13.
See also:  NBP-Lookup

_________________________________________________

                                  NBP-Lookup
*254*

Input names:  [ Type; Zone; HowMany; Count; Interval ]

Input types: [ string; string; integer; integer; integer ]

Defaults: Type = "=" (current type); Zone = "*" (all zones); HowMany = 100; Count = 2; Interval = 8

Output types: 
list; integer

Description: 
Finds out what other entities are on the network. Finds a maximum of HowMany entities of type Type in zone Zone. Count is the number of retries. Interval is the number of seconds between retries. Names is a list of entities found; each entity takes the form of a list of strings( Name Type Zone ).

See also: NBP-Confirm

_________________________________________________

                                NBP-Open
 *255*

Output type: 
integer

Description: Opens AppleTalk under NBP. Must be called before using any of the other NBP primitives.

See also:  NBP-Close

_________________________________________________

                                     NBP-Register
*255*

Input names: 
[ Name; Type; Count; Interval; Verify ]

Input types: [ string; string; integer; integer; boolean ]

Defaults: Name = User Name as entered in the Sharing Setup Control Panel; Type = “=”; Zone = “*”; Count = 2; Interval = 8; Verify = FALSE

Output types: 
integer

Description:  Register the Name and Type on the AppleTalk network under NBP. Count is the number of retries. Interval is the number of seconds between retries. If Verify is TRUE, Name must be unique to the network.
See also: NBP-Lookup